{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Orbit Simulator Tutorial\n",
    "\n",
    "The FSSC Orbit Simulator, **gtorbsim**, is a spacecraft attitude calculator. It has a number of capabilities based on the code already implemented in the general purpose scheduling and planning system TAKO (Timeline Assembler Keyword Oriented) at the Fermi Science Support Center.\n",
    "\n",
    "It is anticipated, however, that the typical end user will only need a subset of the overall functionality of this tool. Primarily, a Guest Investigator would use it to generate a spacecraft data file to use in conjunction with gtobssim to simulate Fermi-LAT observations.\n",
    "\n",
    "This tutorial provides some examples of how to run the **gtorbsim** application. This tool generates a spacecraft data file that is an input for some of the Fermitools. For example, the user may need to run this tool before running gtobssim in order to generate a simulated observation.\n",
    "\n",
    "The main purpose of this simulator is:\n",
    "\n",
    "1. To calculate spacecraft attitude, that is where the local body frame axes are oriented relative to the sky\n",
    "\n",
    "2. To determine when events such as entry/exit in South Atlantic Anomaly (SAA) will take place\n",
    "\n",
    "The above must be accomplished starting with a series of pointing commands. The output of the orbit simulator is a FITS spacecraft data file.\n",
    "\n",
    "You may use the spacecraft data file provided by the FSSC, but in many cases you will probably need to generate that file if you want to perform a particular analysis of simulated data.\n",
    "\n",
    "» [Fermitools References](https://fermi.gsfc.nasa.gov/ssc/data/analysis/scitools/references.html)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Steps\n",
    "\n",
    "1. **Observation Modes**\n",
    "\n",
    "    Observation Modes available in gtorbsim.\n",
    "\n",
    "\n",
    "2. **Spacecraft Ephemeris**\n",
    "\n",
    "    Ephemeris files that gtorbsim can handle.\n",
    "\n",
    "\n",
    "3. **Initial spacecraft position**\n",
    "4. **The South Atlantic Anomaly region**\n",
    "5. **Earth Limb**\n",
    "6. **Run gtorbsim**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 1. Observation Modes\n",
    "\n",
    "The first input you will have to provide to gtorbsim is the observation mode strategy. Several operational modes are planned for Fermi, but the spacecraft will acquire scientific data only in survey and pointed modes.\n",
    "\n",
    "The **sky survey mode** is basically zenith pointed throughout the orbit and has two sub modes: 1) with rocking, and 2) without rocking. Rocking provides more uniform sky coverage and allows for complete sky coverage within a shorter period of time. Different rocking profiles may be implemented, (square or sinusoid) with a basic 2-orbit period and a 60-degree maximum amplitude (above and below the orbit plane).\n",
    "\n",
    "In **pointed observation mode**, the Z-axis of the observatory is commanded to point at a celestial target.\n",
    "\n",
    "With the **gtorbsim** tool you may choose to calculate the attitude in survey or pointed mode. In survey mode you may choose between two options: fixed or profiled. \n",
    "\n",
    "In fixed survey mode the spacecraft does a sky survey with a specified offset with respect to its local zenith for one orbit, and then uses the opposite offset for the next orbit, and so on. In profiled survey, the spacecraft observes in survey mode according to a specified profile consisting of 17 increasing times and 17 zenith offsets. The 17 increasing times (in seconds) are used to indicate the time that it takes during each cycle to go from a corresponding zenith offset to the next. The 17 angles (in degrees) are the zenith offsets reached at the end of the corresponding time interval. The first and last of these offsets must be identical in order for the profile to be repeated.\n",
    "\n",
    "On the other hand, in pointed mode the spacecraft stares at a specified location in the sky identified by an RA and DEC provided by the user. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 2. Spacecraft Ephemeris\n",
    "\n",
    " The orbit simulator needs to know the spacecraft position in the entire interval of interest in order to properly calculate the attitude, therefore it must be capable of either reading in a file that contains the spacecraft ephemeris, or to calculate one on the fly. The orbit simulator can handle three different types of ephemeris files:\n",
    "\n",
    "1. NASA Flight Dynamic Facility (FDF) format, used for missions such as RXTE\n",
    "\n",
    "2. Satellite Tool Kit (STK) format (also in use for Swift)\n",
    "\n",
    "3. [NORAD Two Line Elements](http://celestrak.com/NORAD/elements) available online in which case the spacecraft position is calculated on the fly. The user may extract the Fermi TLE into a file from this [website](http://celestrak.com/NORAD/elements/science.txt). An example of this type of file is given below:\n",
    "```\n",
    "    FGRST (GLAST)\n",
    "    1 33053U 08029A 09033.78481577 .00000278 00000-0 00000+0 0 1746\n",
    "    2 33053 25.5831 172.9725 0014128 40.2809 319.8772 15.04902884 35615\n",
    "```\n",
    "\n",
    "**Notes**:\n",
    "\n",
    "1. For the tool to work the first line of this file has to be \"GLAST\" and not \"Fermi\".\n",
    "\n",
    "2. Keep in mind that the Two Line Elements files are valid only for a few days. If the spacecraft data file that you may want to create is for a period of time where the ephemeris is not valid your spacecraft data file may not be accurate.\n",
    "\n",
    "3. You should copy and paste the example above into a file for use later in the example."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 3. Initial Spacecraft position\n",
    "\n",
    "The initial spacecraft position in equatorial coordinates should be provided by the user as an input parameter. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 4. The South Atlantic Anomaly region\n",
    "\n",
    "The instrument high voltage power supplies will be protected when the spacecraft traverses the South Atlantic Anomaly (SAA). This will occur about ~15% of the time.\n",
    "\n",
    "Gtorbsim has the capability to handle SAA constrains. The SAA region is appoximated by a polygon, which is specified by the Longitude and Latitude of its vertices. It is passed to the program as an input file where the specification of the polygon is given. In cases where the file is not available, a default hard-coded table of longitude and latitude pairs of vertices will be used.\n",
    "\n",
    "The SAA file that is currently used can be downloaded from here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!wget https://fermi.gsfc.nasa.gov/ssc/data/analysis/scitools/data/OrbSim/L_SAA_2008198.03"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 5. Earth Limb\n",
    "\n",
    "The Earth Limb Tracing maneuvering is an optional feature that can easily be enabled/disabled using the appropriate input parameter in gtorbsim. This maneuvering consists of tracing the Earth Limb if a target is Earth-occulted.\n",
    "\n",
    "Targets are assumed to be occulted if their Earth angle (angle between target and the Earth limb) is smaller or at most equal to 30 degrees. Once the target is occulted by the Earth, the orbit simulator finds when is visible again, and where from the Earth Limb is coming out. From the above it finds the angular separation between the in-occult and out-occult position. Finally, the orbit simulator let the local z-axis to sweep equal angles in equal times during its motion along the Earth Limb. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 6. Run gtorbsim\n",
    "\n",
    "This section shows different ways to generate **survey mode** spacecraft data file. To generate a realistic pointed mode observation a timeline generated by TAKO is needed. The FSSC does not provide the user with that tool.\n",
    "\n",
    "**If you need to run a realistic pointed mode observation, please contact the [FSSC](fermihelp@milkyway.gsfc.nasa.gov).**\n",
    "\n",
    "There are different ways to enter the parameters in the tool: By answering a prompt or as a list in a command line, or using an input file. For this reason, the very first input of the simulator is the type of input, which can either be \"console\" or \"file\".\n",
    "\n",
    "An example of init file is given below: "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "start_MJD = 54867\n",
    "stop_MJD = 54923\n",
    "TLType = SINGLE\n",
    "Timeline = |SURVEY|+50.0|\n",
    "EphemFunc = tlederive\n",
    "EphemName = FERMI_TLE_09033.78481577.tle\n",
    "Units = 1.0\n",
    "Resolution = 1\n",
    "Initial_RA = 0\n",
    "Initial_DEC = 0\n",
    "saafunc = saa\n",
    "saafile = L_SAA_2008198.03\n",
    "OutPutFile = spacecraft_data_file_FERMI_TLE_09033.78481577.fits\n",
    "EAA = 20\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For the list of inputs refer to the [gtorbsim](https://fermi.gsfc.nasa.gov/ssc/data/analysis/scitools/help/gtorbsim.txt) help file.\n",
    "\n",
    "If the inputs are given in a file you can run the tool like this: "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "prompt> gtorbsim\n",
    "Type of input {file or console}[file]\n",
    "Input Type is: file\n",
    "Name of init file[] spacecraft_data_file_FERMI_TLE_09033.78481577.init\n",
    "Earth Avoidance Angle: 20 degrees\n",
    "No target found in occultation\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Otherwise you can run the tool in this way: "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "prompt> gtorbsim EAA=20\n",
    "Type of input {file or console}[file] console\n",
    "Input Type is: console\n",
    "start MJD[] 54867\n",
    "stop MJD[] 54923\n",
    "Timeline Type {TAKO, ASFLOWN or SINGLE}[TAKO] SINGLE\n",
    "Timeline SINGLE Command[|SURVEY| +35.0 |]\n",
    "Ephemeredis file name[] FERMI_TLE_09033.78481577.tle\n",
    "Ephemeredis function name[xyzll_eph] tlederive\n",
    "Conversion factor to Km[1]\n",
    "Time resolution in minutes[1]\n",
    "Initial RA[] 0\n",
    "Initial DEC[] 0\n",
    "OutPut File[] spacecraft_data_file_FERMI_TLE_09033.78481577.fits\n",
    "SAA file definition[] L_SAA_2008198.03\n",
    "Earth Avoidance Angle: 20 degrees\n",
    "No target found in occultation\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The spacecraft data file generated with this example could be downloaded from [here](https://fermi.gsfc.nasa.gov/ssc/data/analysis/scitools/data/OrbSim/spacecraft_data_file_FERMI_TLE_09033.78481577.fits). Keep in mind that this spacecraft data file is accurate only for the first few days.\n",
    "\n",
    "Another spacecraft file generated with different ephemeris could be downloaded from [here](https://fermi.gsfc.nasa.gov/ssc/data/analysis/scitools/data/OrbSim/spacecraft_data_file_FERMI_EPH_2009012_2009068_00.fits)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Related Tools\n",
    "\n",
    "* [gtobssim](https://fermi.gsfc.nasa.gov/ssc/data/analysis/scitools/help/gtobssim.txt)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.14"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
